DecisionNode LogoDecisionNodeDocs
Docs/Core Concepts

Context Engine

DecisionNode uses a local RAG engine to surface relevant decisions via semantic search. This page explains how decisions get embedded, stored, and retrieved.

How it works

  • 1. Embedding Vectorization

    When you save a decision, DecisionNode converts it to a vector embedding using Google Gemini's gemini-embedding-001 model. The text that gets embedded is a combination of the decision's fields:

    {scope}: {decision}. {rationale} {constraints}

    For example: "UI: Use Tailwind CSS for all styling. Consistent design tokens. No arbitrary values Use @apply only for base components"

  • 2. Storage Local vector store

    Vectors are stored in vectors.json alongside your decisions. Each entry maps a decision ID to its vector and a timestamp of when it was embedded. No external vector database needed.

    { "ui-001": { "vector": [0.12, -0.45, ...], "embeddedAt": "2024-..." } }

    Global decisions have their own separate vectors.json in ~/.decisionnode/.decisions/_global/.

  • 3. Retrieval Cosine similarity search

    When you or your AI searches, the query text is embedded using the same model, then compared against every stored vector using cosine similarity. Results below the configured threshold (default 0.3) are filtered out, and the remaining matches are returned ranked by score. Only active decisions are searched — deprecated decisions are skipped, but their embeddings are kept so re-activating is instant. Deleting a decision removes both the decision and its embedding permanently.

    Global decisions are included in every search alongside project decisions.

    • Conflict detection

    When you add a new decision, DecisionNode checks for similar existing decisions using a 75% similarity threshold. This works in both the CLI and MCP, but behaves differently:

    CLI (decide add)

    You're shown the similar decisions and asked to confirm:

    ⚠️ Similar decisions found:

    ui-001: Use Tailwind CSS for all styling... (89% similar)

    Continue anyway? (y/N):

    MCP (add_decision)

    The decision is not added. Instead, the similar decisions are returned so the AI can act on them — it might update the existing decision, deprecate it and re-add, or re-call add_decision with force=true to add anyway.

    { "success": false, "reason": "similar_decisions_found", "similar": [ { "id": "ui-001", "decision": "Use Tailwind CSS...", "similarity": "89%" } ] }

    If your API key isn't configured, the conflict check is silently skipped and the decision is added directly.

    Explicit retrieval

    The RAG retrieval is explicit, not implicit. The AI actively calls the search_decisions MCP tool to retrieve context — decisions are not automatically injected into a system prompt.

    This means the AI only retrieves what it needs, when it needs it, keeping the context window focused and relevant.

    CLI usage

    # Semantic search
decide search "how should we handle error logging?"
# Returns matches ranked by similarity score

# Check embedding health
decide check
# Shows which decisions are embedded vs missing vectors

# Embed any unembedded decisions
decide embed
# Generates vectors for decisions that failed or were imported

# Remove orphaned vectors
decide clean
# Cleans up vectors for decisions that no longer exist

    Why local?

    Fast retrieval

    Vector comparison happens in milliseconds on your machine. No network round-trips for search.

    Private

    Decisions stay on your machine. The only external call is to Gemini's embedding API when creating vectors — and that's stateless.

    No infrastructure

    No Pinecone, no Chroma, no database. Vectors are stored in a JSON file that loads into memory.